docs: Add note for the removal of GtkFileChooserButton

Point developers in the direction of GtkButton and GtkFileChooserNative.

diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md
index c4024c9c2f12b0389d0ea9b0f7cfb9981c90a2e4..461be381974d3fd50f84b3ce1d882a15bde8fa34 100644 (file)
--- a/docs/reference/gtk/migrating-3to4.md
+++ b/docs/reference/gtk/migrating-3to4.md
@@ -1149,6 +1149,14 @@ pointer coordinates as inout arguments any more, but as normal in ones.
 
 See: gtk_tree_view_get_tooltip_context(), gtk_icon_view_get_tooltip_context()
 
+### Stop using GtkFileChooserButton
+
+The `GtkFileChooserButton` widget was removed, due to its shortcomings in
+the user interaction. You can replace it with a simple #GtkButton that
+shows a #GtkFileChooserNative dialog when clicked; once the file selection
+has completed, you can update the label of the #GtkButton with the selected
+file.
+
 ## Changes to consider after the switch
 
 GTK 4 has a number of new features that you may want to take